Documenting Implementation Decisions with Code Annotations

Software developers make various decisions when implementing software. For instance, they decide on how to implement an algorithm most efficiently or in which way to process user input. When code is revisited during maintenance, the underlying decisions need to be understood and possibly adjusted to the current situation. Common documentation approaches like JavaDoc neither cover knowledge related to decisions explicitly, nor are they integrated closely with knowledge management. In consequence, decision knowledge is rarely documented and therefore inaccessible, especially when developers have left the team. So, effective maintenance is hindered. We have developed an annotation model for decision knowledge and integrated it with the knowledge management tool UNICASE. The approach enables developers to document decisions within code without tool switches to lower their documentation effort. Afterwards, maintainers can exploit the embedded decision knowledge and follow links to external knowledge. This paper presents the approach and evaluation results of a first case study, which indicate its practicability.